2020.2

Itential Automation Gateway

On this page:

HTTPS Install

Overview

Itential Automation Gateway (IAG) utilizes HAProxy for HTTPS connections. Should you prefer another service, feel free to adapt this configuration guide to match your environment.

⚠ Note: IAG itself only supports HTTP. Making HTTPS requests to IAG without the proper setting may cause the web server to become unresponsive.

The general steps to configure HAProxy are as follows:

  • Log into the server as root, or a privileged user that has access to sudo. All commands herein require privilege escalation.
  • Install HAProxy.
  • Create keys and certificates.
  • Modify the configuration file.
  • Enable the service.
  • Validate the service.

Install HAProxy

In the most simple case, HAProxy can be easily installed using the yum package manager, via the yum install command. Should you require a more up-to-date version, HAProxy also provides an installation path via their source files directly.

yum install haproxy

Certificate Authority Signed Certificates

The private key must be created and the certificate request must be submitted to a trusted certificate authority (CA) for signing. Your certificate authority should return the following set of files.

  • Signed certificate
  • Intermediate CA certificate
  • Root CA certificate

After the signed certificate is received, the final configuration of a secure Itential instance should occur.

⚠ Note: The commands provided in this section should be considered a simple reference implementation. Additional TLS extensions may be added as desired (such as the subject alternate name). Your company's internal procedures or certificate authority's procedures should be consulted for more detailed instructions on creating a certificate request.

Before Certificate Authority Signature

Itential Automation Gateway can be configured to connect to each of its external systems using TLS certificate-based encryption. Use the following openssl command to create a new private key and certificate request.

mkdir /etc/ssl/itential
openssl req -newkey rsa:2048 -keyout /etc/ssl/itential/itential.key -out /etc/ssl/itential/itential.csr

Complete the following fields to create the security certificates for your Itential configuration.

Field Name Description
Country The two-letter country code where your certificate authority resides.
State or Province The name of the state or province where your certificate authority resides.
Locality The name of the city where your certificate authority resides.
Organization The name of your company.
Organizational Unit The name of your department or program.
Common Name For server certificates, the common name should match the FQDN of the server.
Email Address Your email address.
Challenge Password Supply a challenge password for the certificate request.
Company Name (optional) Supply a company name for the certificate request.


Verify the output.

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:US
State or Province Name (full name) []:GA
Locality Name (eg, city) [Default City]:ATLANTA
Organization Name (eg, company) [Default Company Ltd]:ITENTIAL
Organizational Unit Name (eg, section) []:QA
Common Name (eg, your name or your server's hostname) []:*.itential.local
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:ITENTIAL

Perform the following steps:

  1. Set the PEM pass phrase to a secure value.
  2. Set the common name of the certificate to the IP address or FQDN assigned to the server.
  3. The specific settings for the private key in the previous commands may be dictated by your organization's internal security policy.
  4. The common name of a server certificate should the same as the FQDN its clients are configured to connect to. For example, when signing certificates for the MongoDB server, if the common name of the certificate request is my-itential-server.pronghorn.io, the IAP properties.json configuration must use my-itential-server.pronghorn.io in the URL.
  5. If the certificate request is signed with an FQDN but the application is configured with an IP address, the connection will likely fail. The subject alternate name TLS extension may be used to provide a list of authorized names that may be used to connect to the server. A common usage pattern for the subject alternate name is to configure the common name with the FQDN and configure the IP address of the server as the subject alternate name.

After Certificate Authority Signature

Once you have received the signed certificate back from your trusted certificate authority, you should receive three certificate files.

File Description
itential.cert Server certificate.
intermediate_ca.cert Intermediate CA certificate.
root_ca.cert Root CA certificate.


Use the following steps to install the certificates:

  1. Copy the server, intermediate CA and root CA certificates to the /etc/ssl/itential directory, and verify that the server certificate and private key modules are consistent before installing the certificate.

    openssl rsa -noout -modulus -in /etc/ssl/itential/itential.key | openssl md5
openssl x509 -noout -modulus -in /etc/ssl/itential/itential.cert | openssl md5

  2. Verify the key and certificate match in the output.

    (stdin)= e5b26b7e708aa699927532d6c836db02
(stdin)= e5b26b7e708aa699927532d6c836db02

  3. Verify the issuer of the server certificate matches the subject of the intermediate CA certificate.

    openssl x509 -noout -in /etc/ssl/itential/itential.cert -text | grep Issuer:
openssl x509 -noout -in /etc/ssl/itential/intermediate_ca.cert | grep Subject:

  4. Verify the certificate chain matches in the output.

    Issuer: C=US, ST=GA, L=Atlanta, O=Itential, LLC., OU=UAT, CN=db01
Subject: C=US, ST=GA, L=Atlanta, O=Itential, LLC., OU=UAT, CN=db01

  5. Verify the issuer of the intermediate CA certificate matches the subject of the root CA certificate.

    openssl x509 -noout -in /etc/ssl/itential/intermediate_ca.cert | grep Issuer:
openssl x509 -noout -in /etc/ssl/itential/root_ca.cert | grep Subject:

  6. Verify the certificate chain matches in the output.

    Issuer: C=US, ST=GA, L=Atlanta, O=Itential, LLC., OU=UAT, CN=db01
Subject: C=US, ST=GA, L=Atlanta, O=Itential, LLC., OU=UAT, CN=db01

  7. Combine the intermediate CA and root certificates into a single certificate file.

    sh -c "cat /etc/ssl/itential/intermediate_ca.cert /etc/ssl/itential/root_ca.cert > /etc/ssl/itential/itential_ca_chain.cert"

  8. Verify the files in /etc/ssl/itential match the sample output.

    $ ls -1 /etc/ssl/itential
intermediate_ca.cert
itential.csr
itential.cert
itential.key
itential.keycert
itential_ca_chain.cert
root_ca.cert

  9. When using CA-signed certificates, it is likely the intermediate CA and root certificates will be in the chain of trust. Confirm the itential_ca_chain.cert file is in the following format.

    -----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

  10. Add the intermediate CA and root certificates to the system trust store.

    cp /etc/ssl/itential/itential_ca_chain.cert /etc/pki/ca-trust/source/anchors/
update-ca-trust

Self-Signed Certificates

Optionally, you can create a self-signed certificate to use while you are waiting for your certificate to be signed by a trusted authority. Ensure that you enter the following openssl commands one at a time to avoid issues with password prompts being polluted by the script commands.

mkdir /etc/ssl/itential

openssl genrsa -des3 -out /etc/ssl/itential/root_ca.key 2048

openssl req -x509 -new -nodes -key /etc/ssl/itential/root_ca.key -sha256 -days 1024 -out /etc/ssl/itential/root_ca.pem

openssl req -new -nodes -out /etc/ssl/itential/itential.csr -newkey rsa:2048 -keyout /etc/ssl/itential/itential.key

cat > /etc/ssl/itential/san_v3.txt << EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = *.itential.local
EOF

openssl x509 -req -in /etc/ssl/itential/itential.csr -CA /etc/ssl/itential/root_ca.pem -CAkey /etc/ssl/itential/root_ca.key -CAcreateserial -out /etc/ssl/itential/itential.crt -days 500 -sha256 -extfile /etc/ssl/itential/san_v3.txt

chown -R root:root /etc/ssl/itential
chmod -R go-rwx /etc/ssl/itential

Modify the HAProxy Configuration

The HAProxy server is used to terminate HTTPS/TLS connections from clients and proxy them to the backend of the Automation Gateway server.

The HAProxy server comes with a well-defined default configuration file. Modify the default configuration to include frontend and backend definitions (see example below). To revert the proxy, simply remove any deviations from the default configuration.

⚠ Note: When using Itential Automation Gateway with Itential Automation Platform (IAP), the HAProxy configuration used for one system must be compatible with the other. Most notably, the timeouts in Gateway's HAProxy must be at least as large as that of Platform's Automation Gateway adapter (currently the request.attempt_timeout setting).

$ vi /etc/haproxy/haproxy.cfg

# NOTE: Use these sections to modify the configuration to suit your environment. DO NOT fully overwrite the default configuration with these snippets.

global
  # global configuration
  user        haproxy
  group       haproxy
  daemon
  tune.ssl.default-dh-param 2048

defaults
  # default configuration
  # Timeouts should be custom fitted to your environment, and the maximum time of your longest running executions
  # The examples below allow 15 seconds for a client to connect to the server, and 30 minutes for a long running script to finish
  mode http
  timeout connect 15s
  timeout client 30m
  timeout server 30m

frontend automation-gateway
  bind *:8443 ssl crt /etc/ssl/itential/itential.pem force-tlsv12 ciphers DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256
  rspadd Strict-Transport-Security:\ max-age=31536000;\ includeSubDomains
  option forwardfor except 127.0.0.1
  default_backend automation-gateway

backend automation-gateway
  server localhost 127.0.0.1:8083 check

Enable the Service

Enable the HAProxy server to start on boot, and start the service.

$ systemctl enable haproxy
Created symlink from /etc/systemd/system/multi-user.target.wants/haproxy.service to /usr/lib/systemd/system/haproxy.service.

$ systemctl start haproxy

Validate the Service

Ensure the HAProxy service has successfully started and is in an active (running) state.

$ systemctl status haproxy
● haproxy.service - HAProxy Load Balancer
   Loaded: loaded (/usr/lib/systemd/system/haproxy.service; enabled; vendor preset: disabled)
   Active: active (running) since Mon 0000-00-00 00:00:00 EDT; 4s ago
 Main PID: 8339 (haproxy-systemd)
   CGroup: /system.slice/haproxy.service
           ├─8339 /usr/sbin/haproxy-systemd-wrapper -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid
           ├─8340 /usr/sbin/haproxy -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -Ds
           └─8341 /usr/sbin/haproxy -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -Ds

Jan 1 00:00:00 localhost.localdomain systemd[1]: Started HAProxy Load Balancer.
Jan 1 00:00:00 localhost.localdomain haproxy-systemd-wrapper[8339]: haproxy-systemd-wrapper: executing /usr/sbin/haproxy -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -Ds

Troubleshooting

If the service does not successfully start, then you will need to follow the standard troubleshooting pattern for services:

  • Monitor the system logs via journalctl commands.
  • Modify the configuration file, or your environment, in response to the log messages.
  • Restart the service.

Helpful Logging Commands

Useful commands for logging are referenced below.

# See the last 100 lines of the log file
journalctl -n 100

# See the last 100 lines of the log file specifically for the HAProxy service
journalctl -u haproxy -n 100

# Read from the logs indefinitely, starting with the last few logs, specifically for the HAProxy service
journalctl -u haproxy -f

Configure SELinux Policies

For HAProxy to work in an SELinux environment which is set to Enforcing, additional policies need to be modified. Below is an example of flipping the haproxy_connect_any boolean. Additional configuration may be required based on your particular security architecture.

setsebool -P haproxy_connect_any=True

Configure Firewall Rules

In order to ensure the HAProxy instance can be reached externally, configure your firewall to allow the specified ports through. The following is a simple example using the default firewall and its associated firewall-cmd command.

firewall-cmd --zone=public --add-port=8443/tcp --permanent
firewall-cmd --reload

Validate Connectivity

Use the following to ensure that a curl command will delivery a satisfactory response based on your specific HAProxy configuration.

curl https://localhost:8443

For more advanced troubleshooting, you can supply flags to skip ssl validation, display headers, increase verbosity, etc.

curl -v -k -L -D- https://localhost:8443

Web Browser Validation

To test a self-signed certificate with a browser, you will need to import the appropriate root_ca file, from /etc/ssl/itential, into your operating system and enable the system to trust that key. Prior to doing so, browsers such as Chrome will reject your key outright and not allow you to replicate the results from the local curl test.